<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
<head>

<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
<title>Utility Methods : DataMapper ORM - User Guide</title>

<link rel="shortcut icon" type="image/png" href="../images/favicon.png" />
<link rel="stylesheet" type="text/css" media="all" href="../css/userguide.css" />
<link rel="alternate" type="application/rss+xml" title="Datamapper ORM Updates Feed" href="/rss.xml" />

<meta http-equiv="expires" content="-1" />
<meta http-equiv= 'pragma' content="no-cache" />
<meta name="robots" content="all" />

</head>

<body>

<!-- START NAVIGATION -->
<div id="nav"><div id="nav_inner"></div></div>
<div id="nav2"><a name="top">&nbsp;</a><a id="nav_toggle" href="#"><img src="../images/nav_toggle_darker.jpg" width="154" height="43" border="0" title="Toggle Table of Contents" alt="Toggle Table of Contents" /></a></div>
<div id="masthead">
<table cellpadding="0" cellspacing="0" border="0" style="width:100%">
<tr>
<td><h1>DataMapper ORM</h1></td>
<td id="breadcrumb_right"><a href="toc.html">Table of Contents Page</a></td>
</tr>
</table>
</div>
<!-- END NAVIGATION -->

<!-- START BREADCRUMB -->
<table cellpadding="0" cellspacing="0" border="0" style="width:100%">
<tr>
<td id="breadcrumb">
<a href="/">Datamapper ORM Home</a> &nbsp;&#8250;&nbsp;
<a href="../index.html">User Guide Home</a> &nbsp;&#8250;&nbsp;
Utility Methods
</td>
</tr>

</table>
<!-- END BREADCRUMB -->

<br clear="all" />


<!-- START CONTENT -->
<div id="content">


<h1>Utility Methods</h1>

<h4>Subsections</h4>
<ul>
	<li><a href="#exists">Exists</a> - Does an object exist?</li>
	<li><a href="#clear">Clear</a> - Reset an object.</li>
	<li><a href="#reinitialize_model">Reinitialize Model</a> - Reload the configuration information for a model.</li>
	<li><a href="#query">Query</a> - Run a RAW SQL query.</li>
	<li><a href="#add_table_name">Add Table Name</a> - Add the table name to a field.</li>
	<li><a href="#check_last_query">Check Last Query</a> - Output the last query.</li>
</ul>

<h2 id="exists">Exists</h2>
<p>Exists is a simple function that returns <dfn>TRUE</dfn> or <dfn>FALSE</dfn> depending on whether the object has a corresponding database record. For example:</p>

<p>This method works by looking at one of two variables:</p>
<ul>
	<li>If the <var><i>$id</i></var> field is set, then this returns <dfn>TRUE</dfn> if the field is not <kbd>empty()</kbd>.</li>
	<li>Otherwise, this field returns <dfn>TRUE</dfn> if the <var><i>$all</i></var> array contains at least one item.</li>
</ul>
<p>
	This means that an existing record with an <var><i>$id</i></var> of <dfn>0</dfn> <strong>does not "exist"</strong>.
	This is to be consistent with the idea that an empty <var><i>$id</i></var> implies a new record.
</p>

<pre>
<var>$id </var><kbd>= </kbd><var>42</var><kbd>;

</kbd><samp>// Get user
</samp><var>$u </var><kbd>= new </kbd><var>User</var><kbd>();
</kbd><var>$u</var><kbd>-&gt;</kbd><var><u>get_by_id</u></var><kbd>(</kbd><var>$id</var><kbd>);

</kbd><samp>// Check if we actually got a user back from the database
</samp><kbd>if (</kbd><var>$u</var><kbd>-&gt;</kbd><var><u>exists</u></var><kbd>())
{
    </kbd><samp>// Yes, we did!
</samp><kbd>}
else
{
    </kbd><samp>// No, we didn't!
</samp><kbd>}</kbd>
</pre>


<p>&nbsp;</p>


<h2 id="clear">Clear</h2>

<p>Clear is used to clear the object of data.</p>

<pre>
<var>$id </var><kbd>= </kbd><var>42</var><kbd>;

</kbd><samp>// Get user
</samp><var>$u </var><kbd>= new </kbd><var>User</var><kbd>();
</kbd><var>$u</var><kbd>-&gt;</kbd><var><u>get_by_id</u></var><kbd>(</kbd><var>$id</var><kbd>);

</kbd><samp>// Show username
</samp><kbd>echo </kbd><var>$u</var><kbd>-&gt;</kbd><var>username</var><kbd>;

</kbd><samp>// Let's say it outputs "foo bar"

// Clear object
</samp><var>$u</var><kbd>-&gt;</kbd><var><u>clear</u></var><kbd>();

</kbd><samp>// Try to show username again
</samp><kbd>echo </kbd><var>$u</var><kbd>-&gt;</kbd><var>username</var><kbd>;

</kbd><samp>// outputs nothing since the object has been cleared</samp>
</pre>


<p>&nbsp;</p>

<h2 id="reinitialize_model">Reinitialize Model</h2>
<p>This method is used to re-configure a model.</p>
<p>
	The initial configuration happens automatically the first time a model is used.
	Sometimes, however, it is necessary to re-initialize a model.
</p>
<p>
	A specific example would be after a user's preferences have been loaded, and the localized language of the application has been changed.
	In this instance, we need to call <var><u>reinitialize_model()</u></var> on the user object to ensure that the correct language is loaded.
</p>
<p class="note">
	Note: this will only affect the object it is called on, and future objects created that are of the same model.<br/>
	Therefore, language changes should be handled as early as possible in the application, before <strong><em>any other models are accessed</em></strong>
</p>
<h3>Example</h3>
<pre>
<samp>// Custom Session class (application/libraries/MY_Session.php)
</samp><kbd>class </kbd><var>MY_Session </var><kbd>extends </kbd><var>CI_Session </var><kbd>{

    function </kbd><var>MY_Session</var><kbd>() {
        </kbd><var><dfn>parent</dfn></var><kbd>::</kbd><var>CI_Session</var><kbd>();
        </kbd><var>$userid </var><kbd>= </kbd><var><b>$this</b></var><kbd>-&gt;</kbd><var>userdata</var><kbd>[</kbd><dfn>'logged_in'</dfn><kbd>];
        if(!empty(</kbd><var>$userid</var><kbd>)) {
            </kbd><var><b>$this</b></var><kbd>-&gt;</kbd><var>logged_in_user </var><kbd>= new </kbd><var>User</var><kbd>(</kbd><var>$userid</var><kbd>);
            </kbd><var><b>$CI</b> </var><kbd>=&amp; </kbd><var><b>get_instance</b></var><kbd>();
            if(</kbd><var><b>$this</b></var><kbd>-&gt;</kbd><var>logged_in_user</var><kbd>-&gt;</kbd><var>language </var><kbd>!= </kbd><var><b>$CI</b></var><kbd>-&gt;</kbd><var>config</var><kbd>-&gt;</kbd><var>item</var><kbd>(</kbd><dfn>'language'</dfn><kbd>)) {
                </kbd><samp>// override default language
                </samp><var><b>$CI</b></var><kbd>-&gt;</kbd><var>config</var><kbd>-&gt;</kbd><var>config</var><kbd>[</kbd><dfn>'language'</dfn><kbd>] = </kbd><var><b>$this</b></var><kbd>-&gt;</kbd><var>logged_in_user</var><kbd>-&gt;</kbd><var>language</var><kbd>;
                </kbd><samp>// reload the user model
                </samp><var><b>$this</b></var><kbd>-&gt;</kbd><var>logged_in_user</var><kbd>-&gt;</kbd><var><u>reinitialize_model</u></var><kbd>();
            }
        }
    }</kbd>
</pre>


<p>&nbsp;</p>


<h2 id="query">Query</h2>
<p>This method functions in the same way as CodeIgniter's <a href="http://codeigniter.com/user_guide/database/queries.html">Query</a> method except that the object is populated with the returned results.</p>

<p>Use this method at your own risk as it will only be as reliable as your query.  I highly recommend using the binding approach so your data is automatically escaped.</p>

<p>The Query method will populate the object with the results so it is very important to remember that you should be querying for data from the objects table.  For example:</p>

<pre>
<samp>// Create user object
</samp><var>$u </var><kbd>= new </kbd><var>User</var><kbd>();

</kbd><samp>// SQL query on users table
</samp><var>$sql </var><kbd>= </kbd><dfn>"SELECT * FROM `users` WHERE `username` = 'Fred Smith' AND `status` = 'active'"</dfn><kbd>;

</kbd><samp>// Run query to populate user object with the results
</samp><var>$u</var><kbd>-&gt;</kbd><var><u>query</u></var><kbd>(</kbd><var>$sql</var><kbd>);</kbd>
</pre>

<p>Obviously you wouldn't use the Query method for the above situation since DataMapper's <a href="get.html">Get</a> method would be more appropriate.</p>

<p>As I mentioned before, it is recommended you use bindings when using the Query method.  For example, doing the same as above but with bindings:</p>

<pre>
<samp>// Create user object
</samp><var>$u </var><kbd>= new </kbd><var>User</var><kbd>();

</kbd><samp>// SQL query on users table
</samp><var>$sql </var><kbd>= </kbd><dfn>"SELECT * FROM `users` WHERE `username` = <var><i>?</i></var> AND `status` = <var><i>?</i></var>"</dfn><kbd>;

</kbd><samp>// Binding values
</samp><var>$binds </var><kbd>= array(</kbd><dfn>'Fred Smith'</dfn><kbd>, </kbd><dfn>'active'</dfn><kbd>);

</kbd><samp>// Run query to populate user object with the results
</samp><var>$u</var><kbd>-&gt;</kbd><var><u>query</u></var><kbd>(</kbd><var>$sql</var><kbd>, </kbd><var>$binds</var><kbd>);</kbd>
</pre>

<p>The <var><i>question marks</i></var> in the query are automatically replaced with the values in the array in the second parameter of the Query method.</p>



<p>&nbsp;</p>

<h2 id="add_table_name">Add Table Name</h2>
<p>This method will add the object's table name to the provided field.</p>
<p>Useful for the <a href="#query">query</a> method, as well as when you need to run more complicated queries using the normal methods from get and get advanced.</p>
<h3>Arguments</h3>
<ul>
	<li><b>$field</b>: A field or array of field names to prepend the table name to.</li>
</ul>
<pre>
<var>$u </var><kbd>= new </kbd><var>User</var><kbd>();
</kbd><var>$u</var><kbd>-&gt;</kbd><var><u>where</u></var><kbd>( </kbd><dfn>'UPPER(' </dfn><kbd>. </kbd><var>$u</var><kbd>-&gt;</kbd><var><u>add_table_name</u></var><kbd>(</kbd><dfn>'name'</dfn><kbd>) . </kbd><dfn>') &lt;&gt;'</dfn><kbd>, </kbd><dfn>'SECRET'</dfn><kbd>)-&gt;</kbd><var><u>get</u></var><kbd>();

</kbd><samp>// Produces</samp>
<var><kbd>SELECT</kbd> <dfn>*</dfn> <kbd>FROM</kbd> `users`
<kbd>WHERE</kbd> <var><b>UPPER</b></var><kbd>(</kbd>`users`<kbd>.</kbd>`name`<kbd>) <></kbd> <dfn>'SECRET'</dfn></b>
</pre>


<p>The benefit of this method is you are no longer hard-coding the table name.  It may or may not be worth it for your application.</p>



<p>&nbsp;</p>

<h2 id="get_sql">Get SQL</h2>
<p>Info on this method has been <a href="getalt.html#get_sql">moved here</a>.</p>



<p>&nbsp;</p>

<h2 id="check_last_query">Check Last Query</h2>
<p>This method allows you to debug the last query that was processed.  In its simplest form, it outputs the last query, formatted and placed inside <tt>&lt;pre&gt;</tt> tags.</p>
<p>You can also pass as the first argument in a two-item array with alternative delimiters, or <dfn>FALSE</dfn> for no delimiters.  The second argument, when <dfn>TRUE</dfn>, prevents the method from automatically outputting the query to the browser.</p>
<h3>Example</h3>
<pre>
<var>$u </var><kbd>= new </kbd><var>User</var><kbd>();
</kbd><var>$u</var><kbd>-&gt;</kbd><var><u>where</u></var><kbd>(</kbd><dfn>'name'</dfn><kbd>, </kbd><dfn>'Joe'</dfn><kbd>)-&gt;</kbd><var><u>get</u></var><kbd>();
</kbd><var>$u</var><kbd>-&gt;</kbd><var><u>check_last_query</u></var><kbd>();</kbd>
</pre>
Outputs to the browser:
<pre>
SELECT `users`.*
FROM `users`
WHERE `users`.`name` = 'Joe'
</pre>


</div>
<!-- END CONTENT -->


<div id="footer">
<p>
<span id="footer_previous">Previous Topic:&nbsp;&nbsp;<a href=""></a>
&nbsp;&nbsp;&nbsp;&middot;&nbsp;&nbsp;</span>
<a href="#top">Top of Page</a>&nbsp;&nbsp;&nbsp;&middot;&nbsp;&nbsp;
<a href="../index.html">User Guide Home</a>
<span id="footer_next">&nbsp;&nbsp;&nbsp;&middot;&nbsp;&nbsp;
Next Topic:&nbsp;&nbsp;<a href=""></a></span>
</p>
<div id="copyrights">
<p><a href="/">Datamapper ORM</a> &nbsp;&middot;&nbsp; Copyright &copy; 2010-2011 &nbsp;&middot;&nbsp; Harro "WanWizard" Verton</p>
<p><a href="license.html">Other License Information</a></p>
</div>
</div>

<script type="text/javascript" src="../js/mootools.js"></script>
<script type="text/javascript" src="../js/menu.js"></script>
<script type="text/javascript">
<!--
	window.addEvent('domready', function() {

		// Create Menu
		var menu = new Menu({
			basepath: '../',
			pagespath: ''
		});

	});
//-->
</script>
</body>
</html>
